This assertion is meant to pin DoD item 2 ("Every requirement has at least one acceptance criterion"), but /at least one acceptance criterion/i also matches the Step 3 failure-path rule you added at spec.md:99 ("include at least one acceptance criterion covering the failure path"). So if someone deleted the DoD completeness gate but left the Step 3 rule, this stays green — the item it names isn't actually covered. The other three assertions in this test (Definition of Done, No vague wording remains, **Assumption:**) are unique, so the section as a whole is pinned; it's just this one item that slips through. Anchoring on the unique bolded lead-in would fix it:

assert.ok(
  body.includes('Every requirement has at least one acceptance criterion'),
  '...'
);

Confirmed. /at least one acceptance criterion/i also matched the Step 3 failure-path rule at spec.md:99, so DoD item 2 was not pinned — removing line 118 left the test green. The assertion now reads body.includes('Every requirement has at least one acceptance criterion'), which occurs only at the DoD line. Verified by mutation: deleting DoD item 2 now turns the test red. The Step 3 failure-path rule stays independently pinned by the boundary test.

Confirmed at head — the exact substring occurs once, only at the DoD item 2 line. The mutation check is appreciated.

Minor, optional — same flavor as the DoD one but not load-bearing: /concrete in user-perceivable terms/i matches both the Step 4 pass (spec.md:111) and DoD item 1 (spec.md:117), so on its own it wouldn't catch Step 4 being removed. The sibling assertion /vague or unmeasurable wording/i is unique to Step 4, so the test still does its job. Leave it or tighten to a Step-4-only phrase (e.g. the search results appear within 2 seconds example) — your preference.

Tightened. The assertion now anchors on the Step 4 rule sentence, body.includes('Make each one concrete in user-perceivable terms'), unique to line 111. The example phrase was not used as the anchor: it would leave the rule deletable while the test stayed green, whereas the rule sentence pins what the assertion message describes. Verified by mutation.

Confirmed — unique to the Step 4 rule sentence at head. And agreed the example phrase would have been the weaker anchor: the rule sentence is what the assertion message names.

The commands/spec.md:NN citations here are accurate against main as it stands, but this PR's own edits shift every one of them down (~+2 lines) and renumber the steps — so on merge they point at the wrong lines, and "file generation (Step 6, lines 114–119)" names a step that's now Step 7. Same root shows in Point 4 (line 30): "the self-review catches only leakage … weasel words [are] not present in spec.md today" reads in the present tense, but this PR is exactly what makes that false. If the doc stays, citing by section/step name and writing the problem statements in past tense ("before this change…") keeps it from contradicting the file it ships with.

Resolved by removing the document. The stale spec.md:NN citations and the present-tense "not present today" statement are removed with it.

like §Overview and Rationale may stay qualitative.

Weak reference - I don't understand where name of section ends. The same for re-read §Functional Requirements — both.

Please use [Link Text](#section-name) formatting. Here and below in this file.

The section references are disambiguated: all five § tokens are replaced with the bold section name (e.g. §Functional Requirements → Functional Requirements), applied throughout the file.

[Link Text](#section-name) was not used because these references point to sections of the generated functional-spec.md and its template, not to headings within spec.md; an anchor in the prompt file would resolve to no target. Bold delimiting removes the ambiguity without a broken link.

Verified at head — zero § tokens remain. And you're right about the anchor links: these are headings of the generated spec (templates/functional-spec-template.md lines 9 and 15), not headings in this file, so (#section-name) would have been a broken link. Bold is the right call.

No vague wording remains in requirements or acceptance criteria.

I guess it is excessive - big part of step 4 was dedicated to this check. If we make LLM to check itself in the same session (the same as asking person "Are you done?") it rarely works - LLM reads from it's own context that everything is completed already and do nothing (as the person answers "Yes" without checking, from memory). So this usually just a waste of tokens.

We may ask it to Grep in the specific file specific word instead - item 3 below.

Item 1 now defers to Step 4 — a one-clause recap plus a cross-reference — instead of restating the check as an independent rule. A Grep was not adopted, for two reasons: the Definition of Done runs at Step 5, before file generation at Step 7, so no file exists on disk to grep — the whole checklist, including the marker sweep, operates on the in-context draft; and vagueness is not a fixed token set, so grepping the named example words would miss other wording.

The deferral reads well — item 1 is now a hand-off to Step 4 rather than a second full pass, and fair pushback on the Grep: at this step nothing is on disk yet, so there's nothing to grep. One heads-up: the checklist's position is affected by the #141 rebase (see the review summary) — items 1–2 can stay pre-write as they are; item 3 is the one that has to move.

Addressed. Definition-of-Done items 1–2 (no vague wording remains; every requirement carries at least one acceptance criterion) remain pre-write self-checks in Step 4, with no user interaction. Item 3's interactive part is relocated to Step 6: post-save resolution of each [NEEDS CLARIFICATION] marker via AskUserQuestion offers the default assumption as the recommended first option (with a free-text option for open-ended markers), then folds the answer back into the requirement and its acceptance criteria. Main's write-first ordering is preserved.

Confirmed at head — items 1–2 are pre-write self-checks in Step 4 with no user interaction, and item 3's interactive part now lives in post-save Step 6. That's the split I was after, and the write-first ordering holds.

In an interactive session, resolve each one with the user

Please be more precise - like using AskUserQuestion tool with reasonable defaults - it would make LLM understand (and, therefore, implement) task better and be proactive for user (don't invent units for metrics).

Done. The interactive branch of item 3 now resolves each marker with the user via AskUserQuestion, offering the assumption it would otherwise make as the recommended first option, with a free-text option for open-ended markers. It remains a confirmable choice rather than an auto-accept, and the unattended branch (**do not stop** / **Assumption:**) is unchanged, so the deliverable is still never gated on an answer. Metric units are not invented: the model proposes a value for the user to confirm, or records an explicit assumption when unattended.

The AskUserQuestion mechanics are what I was after — the assumption as the recommended first option is exactly right. Heads-up though: after rebasing onto #141, this interactive branch can't stay ahead of the file write — in claude -p a dismissed AskUserQuestion ends the turn before the Write ever runs, which is the exact failure #141 restructured this file around. Main's Step 6 now does post-save marker resolution; I'd move these mechanics there. Details in the review summary.

Addressed. The **Assumption:** fallback is removed. An unattended run now leaves the [NEEDS CLARIFICATION] marker in the saved file, per main's contract pinned by the deliverable commands write their file on an unanswered question test. Markers are no longer replaced with assumptions before saving, which aligns spec.md with product/roadmap and with Step 6.
Concretely: the AskUserQuestion marker-resolution now lives in post-save Step 6, after the file is written in Step 5 — no dismissable question precedes the Write, so the claude -p failure mode #141 restructured around is gone.

Confirmed — the AskUserQuestion resolution now sits in Step 6 after the Step 5 write, and the unattended path leaves the marker in the saved file per main's contract. No dismissable question precedes the Write anymore, so the claude -p failure mode is closed.

TL;DR: better to move this file into separate PR. I don't see how it is used here.

The document is removed from this PR. The deferred points (Non-Functional Metrics; Requirement-Priority Signal) will be addressed in their own coordinated PRs.

Verified at head — zero § tokens remain. And you're right about the anchor links: these are headings of the generated spec (templates/functional-spec-template.md lines 9 and 15), not headings in this file, so (#section-name) would have been a broken link. Bold is the right call.

The deferral reads well — item 1 is now a hand-off to Step 4 rather than a second full pass, and fair pushback on the Grep: at this step nothing is on disk yet, so there's nothing to grep. One heads-up: the checklist's position is affected by the #141 rebase (see the review summary) — items 1–2 can stay pre-write as they are; item 3 is the one that has to move.

The AskUserQuestion mechanics are what I was after — the assumption as the recommended first option is exactly right. Heads-up though: after rebasing onto #141, this interactive branch can't stay ahead of the file write — in claude -p a dismissed AskUserQuestion ends the turn before the Write ever runs, which is the exact failure #141 restructured this file around. Main's Step 6 now does post-save marker resolution; I'd move these mechanics there. Details in the review summary.

Confirmed at head — the exact substring occurs once, only at the DoD item 2 line. The mutation check is appreciated.

Confirmed — unique to the Step 4 rule sentence at head. And agreed the example phrase would have been the weaker anchor: the rule sentence is what the assertion message names.

Confirmed at head — items 1–2 are pre-write self-checks in Step 4 with no user interaction, and item 3's interactive part now lives in post-save Step 6. That's the split I was after, and the write-first ordering holds.

Confirmed — the AskUserQuestion resolution now sits in Step 6 after the Step 5 write, and the unattended path leaves the marker in the saved file per main's contract. No dismissable question precedes the Write anymore, so the claude -p failure mode is closed.